Autogenerated HTML docs for v2.28.0-651-g306ee
diff --git a/RelNotes/2.29.0.txt b/RelNotes/2.29.0.txt index ccbe9b7..e430392 100644 --- a/RelNotes/2.29.0.txt +++ b/RelNotes/2.29.0.txt
@@ -92,6 +92,13 @@ when it fails the local check (hence due to atomicity it is known that no certificate is needed). + * "git commit-graph write" learned to limit the number of bloom + filters that are computed from scratch with the --max-new-filters + option. + + * The transport protocol v2 has become the default again. + + Performance, Internal Implementation, Development Support etc. * The changed-path Bloom filter is improved using ideas from an @@ -385,6 +392,23 @@ ancestor, which has been corrected. (merge 0acbf5997f ld/p4-unshelve-fix later to maint). + * "git clone" that clones from SHA-1 repository, while + GIT_DEFAULT_HASH set to use SHA-256 already, resulted in an + unusable repository that half-claims to be SHA-256 repository + with SHA-1 objects and refs. This has been corrected. + + * Adjust sample hooks for hash algorithm other than SHA-1. + (merge d8d3d632f4 dl/zero-oid-in-hooks later to maint). + + * "git range-diff" showed incorrect diffstat, which has been + corrected. + + * Earlier we taught "git pull" to warn when the user does not say the + histories need to be merged, rebased or accepts only fast- + forwarding, but the warning triggered for those who have set the + pull.ff configuration variable. + (merge 54200cef86 ah/pull later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 84544f2ea3 sk/typofixes later to maint). (merge b17f411ab5 ar/help-guides-doc later to maint).
diff --git a/config.txt b/config.txt index f93b683..bf706b9 100644 --- a/config.txt +++ b/config.txt
@@ -340,6 +340,8 @@ include::config/commit.txt[] +include::config/commitgraph.txt[] + include::config/credential.txt[] include::config/completion.txt[]
diff --git a/git-commit-graph.html b/git-commit-graph.html index 93b4d7a..9afc0ca 100644 --- a/git-commit-graph.html +++ b/git-commit-graph.html
@@ -824,6 +824,12 @@ this option is given, future commit-graph writes will automatically assume that this option was intended. Use <code>--no-changed-paths</code> to stop storing this data.</p></div> +<div class="paragraph"><p>With the <code>--max-new-filters=<n></code> option, generate at most <code>n</code> new Bloom +filters (if <code>--changed-paths</code> is specified). If <code>n</code> is <code>-1</code>, no limit is +enforced. Only commits present in the new layer count against this +limit. To retroactively compute Bloom filters over earlier layers, it is +advised to use <code>--split=replace</code>. Overrides the <code>commitGraph.maxNewFilters</code> +configuration.</p></div> <div class="paragraph"><p>With the <code>--split[=<strategy>]</code> option, write the commit-graph as a chain of multiple commit-graph files stored in <code><dir>/info/commit-graphs</code>. Commit-graph layers are merged based on the @@ -932,7 +938,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-07-30 14:18:13 PDT + 2020-09-29 14:47:55 PDT </div> </div> </body>
diff --git a/git-commit-graph.txt b/git-commit-graph.txt index 17405c7..de6b6de 100644 --- a/git-commit-graph.txt +++ b/git-commit-graph.txt
@@ -67,6 +67,13 @@ that this option was intended. Use `--no-changed-paths` to stop storing this data. + +With the `--max-new-filters=<n>` option, generate at most `n` new Bloom +filters (if `--changed-paths` is specified). If `n` is `-1`, no limit is +enforced. Only commits present in the new layer count against this +limit. To retroactively compute Bloom filters over earlier layers, it is +advised to use `--split=replace`. Overrides the `commitGraph.maxNewFilters` +configuration. ++ With the `--split[=<strategy>]` option, write the commit-graph as a chain of multiple commit-graph files stored in `<dir>/info/commit-graphs`. Commit-graph layers are merged based on the
diff --git a/git-config.html b/git-config.html index b8a4734..ab04fe2 100644 --- a/git-config.html +++ b/git-config.html
@@ -3944,6 +3944,25 @@ </p> </dd> <dt class="hdlist1"> +commitGraph.maxNewFilters +</dt> +<dd> +<p> + Specifies the default value for the <code>--max-new-filters</code> option of <code>git + commit-graph write</code> (c.f., <a href="git-commit-graph.html">git-commit-graph(1)</a>). +</p> +</dd> +<dt class="hdlist1"> +commitGraph.readChangedPaths +</dt> +<dd> +<p> + If true, then git will use the changed-path Bloom filters in the + commit-graph file (if it exists, and they are present). Defaults to + true. See <a href="git-commit-graph.html">git-commit-graph(1)</a> for more information. +</p> +</dd> +<dt class="hdlist1"> credential.helper </dt> <dd> @@ -4602,13 +4621,6 @@ skipping more commits at a time, reducing the number of round trips. </p> </li> -<li> -<p> -<code>protocol.version=2</code> speeds up fetches from repositories with many refs by -allowing the client to specify which refs to list before the server lists -them. -</p> -</li> </ul></div> </dd> <dt class="hdlist1"> @@ -7657,8 +7669,7 @@ If set, clients will attempt to communicate with a server using the specified protocol version. If the server does not support it, communication falls back to version 0. - If unset, the default is <code>0</code>, unless <code>feature.experimental</code> - is enabled, in which case the default is <code>2</code>. + If unset, the default is <code>2</code>. Supported versions: </p> <div class="openblock">
diff --git a/gitfaq.html b/gitfaq.html index 1d1c7ba..90af707 100644 --- a/gitfaq.html +++ b/gitfaq.html
@@ -1036,7 +1036,67 @@ </div> </div> <div class="sect1"> -<h2 id="fetching-and-pulling">Hooks</h2> +<h2 id="fetching-and-pulling">Merging and Rebasing</h2> +<div class="sectionbody"> +<div class="dlist" id="long-running-squash-merge"><dl> +<dt class="hdlist1"> +What kinds of problems can occur when merging long-lived branches with squash merges? +</dt> +<dd> +<p> + In general, there are a variety of problems that can occur when using squash + merges to merge two branches multiple times. These can include seeing extra + commits in <code>git log</code> output, with a GUI, or when using the <code>...</code> notation to + express a range, as well as the possibility of needing to re-resolve conflicts + again and again. +</p> +<div class="paragraph"><p>When Git does a normal merge between two branches, it considers exactly three +points: the two branches and a third commit, called the <em>merge base</em>, which is +usually the common ancestor of the commits. The result of the merge is the sum +of the changes between the merge base and each head. When you merge two +branches with a regular merge commit, this results in a new commit which will +end up as a merge base when they’re merged again, because there is now a new +common ancestor. Git doesn’t have to consider changes that occurred before the +merge base, so you don’t have to re-resolve any conflicts you resolved before.</p></div> +<div class="paragraph"><p>When you perform a squash merge, a merge commit isn’t created; instead, the +changes from one side are applied as a regular commit to the other side. This +means that the merge base for these branches won’t have changed, and so when Git +goes to perform its next merge, it considers all of the changes that it +considered the last time plus the new changes. That means any conflicts may +need to be re-resolved. Similarly, anything using the <code>...</code> notation in <code>git +diff</code>, <code>git log</code>, or a GUI will result in showing all of the changes since the +original merge base.</p></div> +<div class="paragraph"><p>As a consequence, if you want to merge two long-lived branches repeatedly, it’s +best to always use a regular merge commit.</p></div> +</dd> +<dt class="hdlist1"> +If I make a change on two branches but revert it on one, why does the merge of those branches include the change? +</dt> +<dd> +<p> + By default, when Git does a merge, it uses a strategy called the recursive + strategy, which does a fancy three-way merge. In such a case, when Git + performs the merge, it considers exactly three points: the two heads and a + third point, called the <em>merge base</em>, which is usually the common ancestor of + those commits. Git does not consider the history or the individual commits + that have happened on those branches at all. +</p> +<div class="paragraph" id="merge-two-revert-one"><p>As a result, if both sides have a change and one side has reverted that change, +the result is to include the change. This is because the code has changed on +one side and there is no net change on the other, and in this scenario, Git +adopts the change.</p></div> +<div class="paragraph"><p>If this is a problem for you, you can do a rebase instead, rebasing the branch +with the revert onto the other branch. A rebase in this scenario will revert +the change, because a rebase applies each individual commit, including the +revert. Note that rebases rewrite history, so you should avoid rebasing +published branches unless you’re sure you’re comfortable with that. See the +NOTES section in <a href="git-rebase.html">git-rebase(1)</a> for more details.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hooks">Hooks</h2> <div class="sectionbody"> <div class="dlist" id="restrict-with-hooks"><dl> <dt class="hdlist1"> @@ -1115,6 +1175,40 @@ don’t wish to remove the carriage returns from your line endings.</p></div> </dd> <dt class="hdlist1"> +Why do I have a file that’s always modified? +</dt> +<dd> +<p> + Internally, Git always stores file names as sequences of bytes and doesn’t + perform any encoding or case folding. However, Windows and macOS by default + both perform case folding on file names. As a result, it’s possible to end up + with multiple files or directories whose names differ only in case. Git can + handle this just fine, but the file system can store only one of these files, + so when Git reads the other file to see its contents, it looks modified. +</p> +<div class="paragraph" id="always-modified-files-case"><p>It’s best to remove one of the files such that you only have one file. You can +do this with commands like the following (assuming two files <code>AFile.txt</code> and +<code>afile.txt</code>) on an otherwise clean working tree:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>$ git rm --cached AFile.txt +$ git commit -m 'Remove files conflicting in case' +$ git checkout .</code></pre> +</div></div> +<div class="paragraph"><p>This avoids touching the disk, but removes the additional file. Your project +may prefer to adopt a naming convention, such as all-lowercase names, to avoid +this problem from occurring again; such a convention can be checked using a +<code>pre-receive</code> hook or as part of a continuous integration (CI) system.</p></div> +<div class="paragraph"><p>It is also possible for perpetually modified files to occur on any platform if a +smudge or clean filter is in use on your system but a file was previously +committed without running the smudge or clean filter. To fix this, run the +following on an otherwise clean working tree:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>$ git add --renormalize .</code></pre> +</div></div> +</dd> +<dt class="hdlist1"> What’s the recommended way to store files in Git? </dt> <dd> @@ -1168,7 +1262,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-05-26 11:29:03 PDT + 2020-09-29 14:47:55 PDT </div> </div> </body>
diff --git a/gitfaq.txt b/gitfaq.txt index 9cd7a59..afdaeab 100644 --- a/gitfaq.txt +++ b/gitfaq.txt
@@ -241,6 +241,59 @@ ignore the upstream changes. A pull consists of a fetch followed immediately by either a merge or rebase. See linkgit:git-pull[1]. +Merging and Rebasing +-------------------- + +[[long-running-squash-merge]] +What kinds of problems can occur when merging long-lived branches with squash merges?:: + In general, there are a variety of problems that can occur when using squash + merges to merge two branches multiple times. These can include seeing extra + commits in `git log` output, with a GUI, or when using the `...` notation to + express a range, as well as the possibility of needing to re-resolve conflicts + again and again. ++ +When Git does a normal merge between two branches, it considers exactly three +points: the two branches and a third commit, called the _merge base_, which is +usually the common ancestor of the commits. The result of the merge is the sum +of the changes between the merge base and each head. When you merge two +branches with a regular merge commit, this results in a new commit which will +end up as a merge base when they're merged again, because there is now a new +common ancestor. Git doesn't have to consider changes that occurred before the +merge base, so you don't have to re-resolve any conflicts you resolved before. ++ +When you perform a squash merge, a merge commit isn't created; instead, the +changes from one side are applied as a regular commit to the other side. This +means that the merge base for these branches won't have changed, and so when Git +goes to perform its next merge, it considers all of the changes that it +considered the last time plus the new changes. That means any conflicts may +need to be re-resolved. Similarly, anything using the `...` notation in `git +diff`, `git log`, or a GUI will result in showing all of the changes since the +original merge base. ++ +As a consequence, if you want to merge two long-lived branches repeatedly, it's +best to always use a regular merge commit. + +[[merge-two-revert-one]] +If I make a change on two branches but revert it on one, why does the merge of those branches include the change?:: + By default, when Git does a merge, it uses a strategy called the recursive + strategy, which does a fancy three-way merge. In such a case, when Git + performs the merge, it considers exactly three points: the two heads and a + third point, called the _merge base_, which is usually the common ancestor of + those commits. Git does not consider the history or the individual commits + that have happened on those branches at all. ++ +As a result, if both sides have a change and one side has reverted that change, +the result is to include the change. This is because the code has changed on +one side and there is no net change on the other, and in this scenario, Git +adopts the change. ++ +If this is a problem for you, you can do a rebase instead, rebasing the branch +with the revert onto the other branch. A rebase in this scenario will revert +the change, because a rebase applies each individual commit, including the +revert. Note that rebases rewrite history, so you should avoid rebasing +published branches unless you're sure you're comfortable with that. See the +NOTES section in linkgit:git-rebase[1] for more details. + Hooks ----- @@ -310,6 +363,39 @@ You can also control this behavior with the `core.whitespace` setting if you don't wish to remove the carriage returns from your line endings. +[[always-modified-files-case]] +Why do I have a file that's always modified?:: + Internally, Git always stores file names as sequences of bytes and doesn't + perform any encoding or case folding. However, Windows and macOS by default + both perform case folding on file names. As a result, it's possible to end up + with multiple files or directories whose names differ only in case. Git can + handle this just fine, but the file system can store only one of these files, + so when Git reads the other file to see its contents, it looks modified. ++ +It's best to remove one of the files such that you only have one file. You can +do this with commands like the following (assuming two files `AFile.txt` and +`afile.txt`) on an otherwise clean working tree: ++ +---- +$ git rm --cached AFile.txt +$ git commit -m 'Remove files conflicting in case' +$ git checkout . +---- ++ +This avoids touching the disk, but removes the additional file. Your project +may prefer to adopt a naming convention, such as all-lowercase names, to avoid +this problem from occurring again; such a convention can be checked using a +`pre-receive` hook or as part of a continuous integration (CI) system. ++ +It is also possible for perpetually modified files to occur on any platform if a +smudge or clean filter is in use on your system but a file was previously +committed without running the smudge or clean filter. To fix this, run the +following on an otherwise clean working tree: ++ +---- +$ git add --renormalize . +---- + [[recommended-storage-settings]] What's the recommended way to store files in Git?:: While Git can store and handle any file of any type, there are some
diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html index 93aa019..e9c1e86 100644 --- a/howto/keep-canonical-history-correct.html +++ b/howto/keep-canonical-history-correct.html
@@ -938,7 +938,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:11 PDT + 2020-09-29 14:49:06 PDT </div> </div> </body>
diff --git a/howto/maintain-git.html b/howto/maintain-git.html index ec063dc..374ee6b 100644 --- a/howto/maintain-git.html +++ b/howto/maintain-git.html
@@ -1469,7 +1469,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:11 PDT + 2020-09-29 14:49:06 PDT </div> </div> </body>
diff --git a/howto/new-command.html b/howto/new-command.html index c18d6c2..6d54970 100644 --- a/howto/new-command.html +++ b/howto/new-command.html
@@ -863,7 +863,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:07 PDT + 2020-09-29 14:49:01 PDT </div> </div> </body>
diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html index 2794678..72ff41b 100644 --- a/howto/rebase-from-internal-branch.html +++ b/howto/rebase-from-internal-branch.html
@@ -895,7 +895,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:11 PDT + 2020-09-29 14:49:05 PDT </div> </div> </body>
diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html index b6e06d7..76ac67b 100644 --- a/howto/rebuild-from-update-hook.html +++ b/howto/rebuild-from-update-hook.html
@@ -847,7 +847,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:11 PDT + 2020-09-29 14:49:05 PDT </div> </div> </body>
diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html index efa8a89..5d33af3 100644 --- a/howto/recover-corrupted-blob-object.html +++ b/howto/recover-corrupted-blob-object.html
@@ -880,7 +880,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:10 PDT + 2020-09-29 14:49:04 PDT </div> </div> </body>
diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html index a8809a8..9300fde 100644 --- a/howto/recover-corrupted-object-harder.html +++ b/howto/recover-corrupted-object-harder.html
@@ -1189,7 +1189,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:10 PDT + 2020-09-29 14:49:05 PDT </div> </div> </body>
diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html index 4d176f7..799a0cf 100644 --- a/howto/revert-a-faulty-merge.html +++ b/howto/revert-a-faulty-merge.html
@@ -1025,7 +1025,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:10 PDT + 2020-09-29 14:49:04 PDT </div> </div> </body>
diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html index b568129..ae3cd8f 100644 --- a/howto/revert-branch-rebase.html +++ b/howto/revert-branch-rebase.html
@@ -907,7 +907,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:07 PDT + 2020-09-29 14:49:01 PDT </div> </div> </body>
diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html index 68abddc..73638df 100644 --- a/howto/separating-topic-branches.html +++ b/howto/separating-topic-branches.html
@@ -841,7 +841,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:09 PDT + 2020-09-29 14:49:04 PDT </div> </div> </body>
diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index b9645fc..1657c00 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html
@@ -1071,7 +1071,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:09 PDT + 2020-09-29 14:49:03 PDT </div> </div> </body>
diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html index c64c726..6601d20 100644 --- a/howto/update-hook-example.html +++ b/howto/update-hook-example.html
@@ -930,7 +930,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:09 PDT + 2020-09-29 14:49:03 PDT </div> </div> </body>
diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html index 864b890..8af7cb4 100644 --- a/howto/use-git-daemon.html +++ b/howto/use-git-daemon.html
@@ -791,7 +791,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:08 PDT + 2020-09-29 14:49:02 PDT </div> </div> </body>
diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html index 54e70fd..809a7d3 100644 --- a/howto/using-merge-subtree.html +++ b/howto/using-merge-subtree.html
@@ -848,7 +848,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:08 PDT + 2020-09-29 14:49:01 PDT </div> </div> </body>
diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html index 033fbc3..63d7a88 100644 --- a/howto/using-signed-tag-in-pull-request.html +++ b/howto/using-signed-tag-in-pull-request.html
@@ -952,7 +952,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-25 15:48:08 PDT + 2020-09-29 14:49:02 PDT </div> </div> </body>
diff --git a/technical/commit-graph-format.txt b/technical/commit-graph-format.txt index 1f86031..b3b5888 100644 --- a/technical/commit-graph-format.txt +++ b/technical/commit-graph-format.txt
@@ -125,7 +125,7 @@ * The rest of the chunk is the concatenation of all the computed Bloom filters for the commits in lexicographic order. * Note: Commits with no changes or more than 512 changes have Bloom filters - of length zero. + of length one, with either all bits set to zero or one respectively. * The BDAT chunk is present if and only if BIDX is present. Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] 